Receiving Low-Level Events

Applications receive events one at a time by asking the Event Manager for

the next available event. You use Event Manager routines to receive (or in

the case of EventAvail, simply to look at) the next available event that is

pending for your application. The Event Manager returns to your application

an EventRecord, which includes the relevant information about that event.

Your application can use the WaitNextEvent, GetNextEvent, and

EventAvail functions to retrieve events from the Event Manager.

GetNextEvent returns the next available event of a specified type. Further,

if the event returned is in the event queue, GetNextEvent removes it from

the queue. EventAvail is just like GetNextEvent, except that if the event

reported is in the event queue, it is left there. EventAvail thus allows your

application to look at the next event in the event queue without actually

processing the event.

You should use the WaitNextEvent function to retrieve an event from the

WaitNextEvent requires four parameters: an event mask, an event record,

a sleep value, and a mouse region. If the function WaitNextEvent returns

successfully, the EventRecord contains information about the retrieved event.

The eventMask parameter selects which events are to be waited for. The sleep

parameter specifies the amount of time (in sleepTicks) that your application

agrees to relinquish the processor if no events are pending for it. When that

time expires or when an event becomes available for your application, the

Process Manager schedules your application for execution. In general, you

should specify a value greater than 0 in the sleep parameter so that other

applications can receive processing time if they need it. Your application

should not sleep more than 15 ticks if you use TextEdit because the fastest

cursor blink occurs every 15 ticks.

The mouseRgn parameter to WaitNextEvent specifies a screen region that

lets you determine the conditions when your application is to receive notice of

mouse-moved events. Your application receives mouse-moved events only

when the mouse is outside of the specified region and your application is the

foreground process. You can use the mouseRgn parameter as a convenient way

to change the shape of the cursor-for example, when the mouse moves from

the content area of a window to the scroll bar.

Note: If your application calls WaitNextEvent, it should not call the

SystemTask procedure.